home *** CD-ROM | disk | FTP | other *** search
/ Chip 1996 November / Chip 11-96.iso / treiber / grafik / datapat / twinor64 / win3x / blackole / bheffect.h_ / bheffect.h
C/C++ Source or Header  |  1994-07-03  |  12KB  |  180 lines
  1.  
  2. /* ========================================================================= */
  3. /* ==                                                                     == */
  4. /* ==   Black Holes V2.00, Warp effects DLL Interface                     == */
  5. /* ==                                                                     == */
  6. /* ==   (c) Datapath UK Ltd, Derby.                                       == */
  7. /* ==   Last modified : July 1994                                         == */
  8. /* ==                                                                     == */
  9. /* ==   Developers are free to use this interface to add their own warp   == */
  10. /* ==   visual effects. The mechanism for doing this is explained fully   == */
  11. /* ==   in the Black Holes online help file. The basic steps are:         == */
  12. /* ==                                                                     == */
  13. /* ==   Warp visual effects are placed in a separate DLL - there can be   == */
  14. /* ==   more than one effect in a single DLL.  Each DLL must provide the  == */
  15. /* ==   two exported routines :                                           == */
  16. /* ==      1.   unsigned short BHGetNumberOfEffects (void);               == */
  17. /* ==      2.   void BHGetEffectsDetails (PTBHEffectDetails);             == */
  18. /* ==                                                                     == */
  19. /* ==   The first simply tells Black holes how many visual effects are    == */
  20. /* ==   contained within the DLL.                                         == */
  21. /* ==   The second fills in an array of TBHEffectDetails with the details == */
  22. /* ==   of each effect in the DLL.  See later for a description of the    == */
  23. /* ==   contents of TBHEffectDetails.                                     == */
  24. /* ==                                                                     == */
  25. /* ==   Place the name of the finished effects DLL in the [DLLs] section  == */
  26. /* ==   of the Black Holes INI file (blackole.ini).                       == */
  27. /* ==   eg :                                                              == */
  28. /* ==                                                                     == */
  29. /* ==       [DLLs]                                                        == */
  30. /* ==       ; list of visual effects dll's                                == */
  31. /* ==       bheffect.dll                                                  == */
  32. /* ==       your_dll.dll                                                  == */
  33. /* ==                                                                     == */
  34. /* ==   The actual DLL should be placed in one of the following           == */
  35. /* ==   directories :                                                     == */
  36. /* ==        1.  The Black Holes directory ( probably \BLACKOLE )         == */
  37. /* ==        2.  The Windows directory ( \WINDOWS )                       == */
  38. /* ==        3.  The Windows System directory ( \WINDOWS\SYSTEM )         == */
  39. /* ==                                                                     == */
  40. /* ========================================================================= */
  41.  
  42. #ifndef _BHEFFECT_DEF_
  43. #define _BHEFFECT_DEF_
  44.  
  45. #ifdef __DLL__
  46. #define EXPORT_FN  _export
  47. #else
  48. #define EXPORT_FN
  49. #endif
  50.  
  51. #include <windows.h>
  52.  
  53. #ifdef __cplusplus
  54. extern "C" {
  55. #endif
  56.  
  57.  
  58. /* ========================================================================== */
  59. /* == Configuration data type for warp effect                              == */
  60. /* ==  Each warp effect can use this type to store whatever configuration  == */
  61. /* ==  data it wants, but -                                                == */
  62. /* ==                                                                      == */
  63. /* ==  DO NOT use it to store pointer values - the value gets written      == */
  64. /* ==  into the .BKH files, and the .INI file, so using a pointer value    == */
  65. /* ==  would cause a crash when Black Holes is run for a second time.      == */
  66. /* ==                                                                      == */
  67. /* ==  This effectively restricts the configuration data to 4 bytes.       == */
  68. /* ==  Datapath Ltd reserve the right to change the TConfigData type to    == */
  69. /* ==  allow more information to be stored in the future.                  == */
  70. /* ========================================================================== */
  71.  
  72. typedef unsigned long TConfigData;
  73.  
  74. /* ========================================================================== */
  75. /* == Structure holding start and end points (in screen coordinates) for   == */
  76. /* == a cursor warp.                                                       == */
  77. /* ========================================================================== */
  78. typedef struct { POINT start;
  79.                  POINT end;
  80.                } TWarpPoints;
  81.  
  82. typedef TWarpPoints FAR * PTWarpPoints;
  83.  
  84. /* ========================================================================== */
  85. /* == Structure to hold effect details for each individual warp effect     == */
  86. /* ==                                                                      == */
  87. /* == effect_name        : Name of effect as presented to user             == */
  88. /* == is_configurable    : Whether it is possible to 'setup' the           == */
  89. /* ==                       effect. If this is TRUE, then 'Configure' (see == */
  90. /* ==                       later) must not be NULL                        == */
  91. /* == init_config_data   : Holds the initial 'config' value of the         == */
  92. /* ==                       effect                                         == */
  93. /* == (*Configure)       : Points to a function which alters the config    == */
  94. /* ==                       data for the particular effect                 == */
  95. /* ==                                                                      == */
  96. /* ==                                                                      == */
  97. /* == (*InitialiseEffect): This is called once, when Black Holes first     == */
  98. /* ==                      starts up. This allows one-time initialisation, == */
  99. /* ==                      or the possibility, say, of putting up your own == */
  100. /* ==                      splash panel saying who wrote the new effects.  == */
  101. /* ==                                                                      == */
  102. /* == (*FreeEffect)     : This is called once, when Black Holes is         == */
  103. /* ==                      closing down.                                   == */
  104. /* ==                                                                      == */
  105. /* == BeginEffect, DoEffect, EndEffect - the routines that actually        == */
  106. /* == warp the cursor from one hole to another.  They are called one       == */
  107. /* == after each other, each one with the same parameters :                == */
  108. /* ==                                                                      == */
  109. /* ==    PTWarpPoints pts   : points to a structure containing the start   == */
  110. /* ==                         and end points of the warp, in screen coords == */
  111. /* ==    HWND hwnd          : Window handle of the Black Hole located at   == */
  112. /* ==                         the entry point.                             == */
  113. /* ==    TConfigData config : the config value to be used for the warp     == */
  114. /* ==    LPDWORD user_data  : pointer to a DWORD, where the developer can  == */
  115. /* ==                         store any extra data desired. The same value == */
  116. /* ==                         is passed to BeginEffect, DoEffect &         == */
  117. /* ==                         EndEffect by Black Holes.                    == */
  118. /* ==                         The value of user_data is not stored in the  == */
  119. /* ==                         .BKH or .INI files.                          == */
  120. /* ==                                                                      == */
  121. /* ==  (*BeginEffect)      : Called immediately before a cursor warp       == */
  122. /* ==                        happens, allows any 'setting up' to be done.  == */
  123. /* ==  (*DoEffect)         : This function warps the cursor between the    == */
  124. /* ==                        start and end points supplied in PTWarpPoints == */
  125. /* ==  (*EndEffect)        : Called immediately after the warp has been    == */
  126. /* ==                        completed, and allows any 'tidying up' to be  == */
  127. /* ==                        done.                                         == */
  128. /* ==                                                                      == */
  129. /* ==  number_of_cursors : Holds the number of different cursors the       == */
  130. /* ==                      uses                                            == */
  131. /* ==                                                                      == */
  132. /* ==  (*LoadCursor)     : Loads the cursors required for the effect,      == */
  133. /* ==                      into an array of HCURSORs, the size of which is == */
  134. /* ==                      defined by 'number_of_cursors' field above.     == */
  135. /* ==                      Returns the number of cursors loaded.           == */
  136. /* ==                                                                      == */
  137. /* ==  (*SelectCursor)   : This routine is called when the mouse cursor    == */
  138. /* ==                      moves over a Black Hole with this effect.       == */
  139. /* ==                      Given the start and end warp points, returns    == */
  140. /* ==                      the index of the cursor to display. The index   == */
  141. /* ==                      should be an integer between 0 and the number   == */
  142. /* ==                      given by number_of_cursors minus 1 (see above). == */
  143. /* ==                                                                      == */
  144. /* ========================================================================== */
  145.  
  146.  
  147. #define MAX_EFFECTNAME_LENGTH    20
  148.  
  149. typedef struct { void            (*Configure)        (TConfigData FAR *, HWND);
  150.                  void            (*InitialiseEffect) (void);
  151.                  void            (*FreeEffect)       (void);
  152.                  void            (*BeginEffect) (PTWarpPoints, HWND, TConfigData, LPDWORD);
  153.                  void            (*DoEffect)    (PTWarpPoints, HWND, TConfigData, LPDWORD);
  154.                  void            (*EndEffect)   (PTWarpPoints, HWND, TConfigData, LPDWORD);
  155.                  unsigned short  (*LoadCursors) (HCURSOR far *);
  156.                  unsigned short  (*SelectCursor)(PTWarpPoints);
  157.                  TConfigData     init_config_data;
  158.                  BOOL            is_configurable;
  159.                  unsigned short  number_of_cursors;
  160.                  char            effect_name[MAX_EFFECTNAME_LENGTH];
  161.                } TBHEffectDetails, FAR * PTBHEffectDetails;
  162.  
  163.  
  164. /* ========================================================================== */
  165. /* == Returns the number of warp effects in the file                       == */
  166. /* ========================================================================== */
  167. unsigned short CALLBACK EXPORT_FN BHGetNumberOfEffects (void);
  168.  
  169. /* ========================================================================== */
  170. /* == Fills the 'details' structure for the number of effects given by     == */
  171. /* == BHGetNumberOfEffects (see above).                                    == */
  172. /* ========================================================================== */
  173. void CALLBACK EXPORT_FN BHGetEffectsDetails(PTBHEffectDetails details);
  174.  
  175. #ifdef __cplusplus
  176. }
  177. #endif
  178.  
  179. #endif
  180.